{smcl}
{* 28jun2006}{...}
{cmd:help mata mm_insheet()}
{hline}


{title:Title}

{p 4 4 2}
{bf:mm_insheet() -- Read spreadsheet file into string matrix (and vice versa)}


{title:Syntax}

{p 8 22 2}
{it:string matrix}
{cmd:mm_insheet(}{it:filename} [{cmd:,} {it:delimiter}{cmd:,} {it:line1}{cmd:,} {it:line2}]{cmd:)}


{p 8 22 2}
{it:string matrix}
{cmd:mm_infile(}{it:filename} [{cmd:,} {it:line1}{cmd:,} {it:line2}]{cmd:)}


{p 8 22 2}
{it:void}{space 9}
{cmd:mm_outsheet(}{it:filename} {cmd:,} {it:s}[{cmd:,} {it:mode}{cmd:,} {it:delimiter}]{cmd:)}


{p 4 8 2}
where

              {it:filename}:  {it:string scalar filename}
             {it:delimiter}:  {it:string scalar delimiter}
                 {it:line1}:  {it:real scalar line1}
                 {it:line2}:  {it:real scalar line2}
                     {it:s}:  {it:string matrix s}
{p 18 26 2}{it:mode}:  {it:string scalar} containing "", "{opt r:eplace}" or "{opt a:ppend}"


{title:Description}

{p 4 4 2} {cmd:mm_insheet()} returns as a string matrix the
contents of a spreadsheet file (ASCII) in which columns
are separated by, e.g., tabs or commas and rows are
separated by the newline character. {it:filename} specifies the
filename. {it:delimiter} specifies the character used to
separate the values. The default value for {it:delimiter}
is {cmd:char(9)} (the tab-character).

{p 4 4 2} {cmd:mm_infile()} returns as a string matrix the
contents of a free-format file (ASCII) in which columns are
separated by one or more blanks and rows are
separated by the newline character.

{p 4 4 2}Specifying {it:line1} (and {it:line2}) with {cmd:mm_insheet()} or
{cmd:mm_infile()} indicates that the file be read
starting with line number {it:line1} (and ending with line number {it:line2}).

{p 4 4 2} {cmd:mm_outsheet()} writes string matrix {it:s} into
an ASCII file. Rows are separated by the newline character.
Columns are separated by {it:delimiter}. The default value
for {it:delimiter} is {cmd:char(9)} (the tab-character).
{cmd:mm_outsheet()} aborts with error if the file
indicated by fn already exists and {it:mode} is omitted or {it:mode}="". Specify
{it:mode}="{opt r:eplace}" to replace an existing file or
{it:mode}="{opt a:ppend}" to append to an existing file.


{title:Remarks}

{p 4 4 2} {cmd:mm_outsheet()} can only be used with string
matrices. To export a real matrix, type
{bind:{cmd:mm_outsheet(}{it:filename}{cmd:, strofreal(}{it:R}{cmd:))}}
where {it:R} is the real matrix (see
{bf:{help mf_strofreal:[M-5] strofreal()}}).


{title:Conformability}

    {cmd:mm_insheet(}{it:filename}{cmd:,} {it:delimiter}{cmd:,} {it:line1}{cmd:,} {it:line2}{cmd:)}:
      {it:filename}:  1 {it:x} 1
     {it:delimiter}:  1 {it:x} 1
         {it:line1}:  1 {it:x} 1
         {it:line2}:  1 {it:x} 1
        {it:result}:  r {it:x} c

    {cmd:mm_infile(}{it:filename}{cmd:,} {it:line1}{cmd:,} {it:line2}{cmd:)}:
      {it:filename}:  1 {it:x} 1
         {it:line1}:  1 {it:x} 1
         {it:line2}:  1 {it:x} 1
        {it:result}:  r {it:x} c

    {cmd:mm_outsheet(}{it:filename}{cmd:,} {it:s}{cmd:,} {it:mode}{cmd:,} {it:delimiter}{cmd:)}:
      {it:filename}:  1 {it:x} 1
             {it:s}:  r {it:x} c
          {it:mode}:  1 {it:x} 1
     {it:delimiter}:  1 {it:x} 1
        {it:result}:  {it:void}


{title:Diagnostics}

{p 4 4 2} {cmd:mm_insheet()} and
{cmd:mm_infile()} abort with error if the file
indicated by {it:filename} does not exist.

{p 4 4 2} {cmd:mm_insheet()} and {cmd:mm_infile()} return a 0 x 0
result if the file indicated by {it:filename} contains 0 bytes.

{p 4 4 2} The number of columns in the matrix returned by
{cmd:mm_insheet()} or {cmd:mm_infile()} is determined by the maximum number of
elements per line found the input file. If an individual input line
contains less than the maximum number of elements, an appropriate number
of empty elements is appended to the right of the row.

{p 4 4 2} {cmd:mm_outsheet()} creates a file containing 0
bytes if {it:s} is a void string matrix (see
{bf:{help m2_void:[M-2] void}}).


{title:Source code}

{p 4 4 2}
{help moremata_source##mm_insheet:mm_insheet.mata},
{help moremata_source##mm_infile:mm_infile.mata},
{help moremata_source##mm_outsheet:mm_outsheet.mata}


{title:Author}

{p 4 4 2} Ben Jann, University of Bern, jann@soz.unibe.ch


{title:Also see}

{p 4 13 2}
Online:  help for
{bf:{help m4_io:[M-4] io -- I/O functions}},
{bf:{help mf_cat:[M-5] cat()}},
{bf:{help moremata}}
